ego (lite) 使用指南 AI Agent 的专属浏览器

ego (lite) 是一个基于 Chromium 的桌面浏览器,让 AI agent 在隔离的 Space 里复用你已登录的浏览器状态(cookie、session、扩展),执行 Web 自动化,同时不打扰你的正常浏览。

免费、开源(MIT)、数据全部本地存储。


一、它解决什么问题

传统方案 痛点 ego (lite) 的做法
Playwright / Puppeteer 起一个空白浏览器,需要重新登录所有网站 共享你已有的登录态,agent 直接在认证环境里工作
Browser Use / agent-browser 每步一个 CLI 命令,逐条往返,慢且费 token agent 写 JS 代码片段,多步操作一次性执行,官方测 2.5x 快、token 更少
ChatGPT Atlas / Perplexity Comet 只能用自家内置 agent 兼容任意外部 agent(Claude Code、Codex、Cursor、Gemini CLI 等)
浏览器扩展 抢你的鼠标焦点、占你的 tab agent 在独立 Space 里操作,你的 tab 完全不受影响

二、核心概念

Space(隔离工作区)

每个 agent 任务在独立的 Space 里运行,拥有自己的 tab、历史、状态。多个 agent 可以同时在不同 Space 并行执行,互不干扰。你随时可以切进去看 agent 在干什么,也可以手动接管。

ego-browser(连接层)

一个 skill 文件,安装到 agent 的 skills 目录里。它把浏览器暴露为一组页内 JavaScript 函数,agent 直接调用——不走 CLI 逐条指令的模式。

Semantic Snapshot(语义快照)

在 Chromium 引擎层面定制的页面结构化文本表示。能穿透跨域 iframe、Shadow DOM、第三方组件(Stripe、Salesforce、React Portal)。用稳定的 @N 引用替代 CSS 选择器,DOM 类名变了也不受影响,且比原始 HTML 省 token。


三、安装(macOS,Windows/Linux 待上线)

方式一:下载 DMG

从 lite.ego.app 下载对应芯片版本(Apple Silicon / Intel)。首次启动会询问是否迁移 Chrome 数据——选"是"后自动复制 profile(不修改 Chrome),agent 立即继承你所有登录态。

安装过程会自动把 ego-browser skill 注册到 agent 的 skills 目录。

方式二:npx 安装 skill

npx skills add citrolabs/ego-lite

只安装 skill 连接层,首次执行浏览器任务时自动安装 ego lite 应用。

方式三:让 agent 自己装

把下面的指令丢给你的 agent:

Read skills/ego-browser/references/install.md and follow the install steps.

安装验证

# 确认 ego-browser CLI 可用
command -v ego-browser

# 快速测试连通性
ego-browser nodejs <<'EOF'
console.log('ego-browser ready')
EOF

四、使用方法

基本流程

在 agent 终端里用 /ego-browser 加自然语言描述任务:

# 关注 Twitter 账号
/ego-browser follow @ego_agent on x.com for me

# 抓取竞品定价
/ego-browser open competitor.com/pricing, capture the pricing table as markdown

# 查看内部系统仪表盘
/ego-browser go to grafana.internal/d/api-latency, screenshot the last 24h panel

agent 会在独立 Space 里打开页面、读取 Snapshot、执行操作、返回结果。

执行模型

agent 不是逐条发 CLI 命令,而是写一段 JS 代码组合多个操作,一次性执行:

navigate("https://x.com/ego_agent") → snapshot() → click(@follow-button) → snapshot()

这就是为什么它比传统 CLI 驱动的方案快——减少了 agent 和浏览器之间的往返次数。


五、V2 API 详解

ego-browser 的 V2 API 暴露为全局 JavaScript 函数,agent 在一段 JS 代码里直接调用。

Space 管理

函数 用途
taskSpace(nameOrId) 创建或恢复一个隔离 Space(按名称新建,按 ID 恢复)
listTaskSpaces() 列出所有活跃 Space
claimTaskSpace(spaceId) 认领一个已有 Space
takeOverTaskSpace(spaceId) 强制接管一个 Space
profiles() 列出浏览器 profile,可通过 taskSpace(name, { profileId }) 指定
task.finish({ keep: [] }) 结束任务,关闭所有 page;keep: ["p2"] 保留指定 page 给用户看

页面观察

函数 用途
page.snapshot() 返回页面的结构化文本(语义快照,token 高效)
page.screenshot({ path }) 截图保存到本地路径
page.url() 获取当前 URL
page.title() 获取页面标题
page.info() 获取页面综合信息

页面导航

函数 用途
page.goto(url) 导航到指定 URL
page.reload() 重新加载页面
page.waitForURL(pattern) 等待 URL 匹配
page.waitForLoadState() 等待页面加载完成

页面交互

函数 用途
page.click(selector) 点击元素
page.dblclick(selector) 双击
page.hover(selector) 悬停
page.fill(selector, value) 填写输入框
page.selectOption(selector, value) 选择下拉选项
page.focus(selector) 聚焦元素
page.press(key) 按键(如 "Enter")
page.dragAndDrop(from, to) 拖拽
page.setInputFiles(selector, files) 上传文件

等待机制

函数 用途
page.waitForSelector(sel, { state }) 等待元素出现/隐藏
page.waitForFunction(fn) 等待自定义条件
page.waitForTimeout(ms) 硬等待(慎用)
page.waitForEvent(type) 等待事件(如 "download")

底层控制(Canvas、富应用场景)

函数 用途
page.mouse.click(x, y) 坐标点击
page.mouse.move(x, y) 鼠标移动
page.mouse.wheel(dx, dy) 滚轮
page.keyboard.type(text) 逐字输入
page.keyboard.press(key) 按键
page.keyboard.paste(text) 粘贴文本
page.evaluate(fn, arg) 在页面上下文执行任意 JS

选择器语法

ego-browser 用多种方式定位元素,优先用 @N 语义引用:

语法 示例 说明
@N @21 Snapshot 里的稳定引用,推荐首选
text= text=Sign in 按文本内容匹配
loc=role: loc=role:button[name='Submit'] 按 ARIA 角色
loc=css: loc=css:#account-home CSS 选择器
loc=href: loc=href:/settings 按链接地址
xpath= xpath=//div[@id='main'] XPath
原始 CSS #login-btn 兜底

六、实战代码示例

打开页面 + 读取内容

ego-browser nodejs <<'EOF'
const task = await taskSpace("inspect example page");
const page = task.page("p1");
await page.goto("https://example.com");
console.log(await page.snapshot());
await task.finish({ keep: [] });
EOF

登录表单填写

ego-browser nodejs <<'EOF'
const task = await taskSpace("login flow");
const page = task.page("p1");
await page.goto("https://app.example.com/login");
// 用 snapshot 里的 @N 引用定位输入框
await page.fill("@21", "user@example.com");
await page.fill("@23", "mypassword");
await page.click("loc=role:button[name='Sign in']");
await page.waitForSelector("loc=css:#dashboard", { state: "visible" });
console.log(await page.snapshot());
await task.finish({ keep: ["p1"] }); // 保留页面给用户看
EOF

截图 + 坐标操作(Canvas/富应用)

ego-browser nodejs <<'EOF'
const task = await taskSpace("spreadsheet edit");
const page = task.page("p1");
await page.goto("https://docs.google.com/spreadsheets/d/...");
const path = await page.screenshot({ path: "/tmp/before.png" });
await page.mouse.click(420, 260, { label: "open cell" });
await page.keyboard.paste("hello\tworld");
await page.screenshot({ path: "/tmp/after.png" });
await task.finish({ keep: ["p1"] });
EOF

恢复之前的 Space(多轮对话)

ego-browser nodejs <<'EOF'
// 用 Space ID 恢复上一轮的工作区
const resumed = await taskSpace(7);
const page = resumed.page("p1");
await page.goto("https://example.com/next-step");
console.log(await page.snapshot());
EOF

文件下载

ego-browser nodejs <<'EOF'
const task = await taskSpace("download report");
const page = task.page("p1");
await page.goto("https://app.example.com/reports");
const [download] = await Promise.all([
  page.waitForEvent("download"),
  page.click("text=Export CSV")
]);
await download.saveAs("/tmp/report.csv");
console.log("Downloaded to:", await download.path());
await task.finish({ keep: [] });
EOF

七、Learnings(站点级可复用技能)

ego-browser 内置了针对特定网站的预制 skill,存放在 skills/ego-browser/learnings/ 下:

站点 内置技能
Google search_and_extract、autocomplete
X (Twitter) timeline、search_users、extract-post
GitHub search-repos、open-issues、repo-stats

每个站点有一个 manifest.json 声明 nodeTools(Node.js 侧工具)和 browserTools(页内工具)。社区可以贡献新站点的 learnings——这是 "Experience Accumulation"(经验积累)特性的基础。


八、兼容的 Agent

Agent 支持方式
Claude Code /ego-browser skill
Codex skill 目录
Cursor skill 目录
Gemini CLI skill 目录
Kiro / Continue / OpenCode skill 目录
自定义 Agent 只要能执行 shell 命令就行

不绑定特定模型,不需要集成 SDK。


九、架构

┌──────────────────────────────────────────┐
│           ego (lite) 浏览器               │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐    │
│  │ 你的 Tab │ │ Space 1 │ │ Space 2 │    │
│  │(不受影响)│ │(Agent A)│ │(Agent B)│    │
│  └─────────┘ └────┬────┘ └────┬────┘    │
│                    │           │          │
│              CDP (Chrome DevTools Protocol)│
└──────────────┬─────┴───────────┘──────────┘
               │
        ┌──────┴──────┐
        │ ego-browser  │  ← skill 文件 + TypeScript 运行时
        │  (连接层)     │     暴露 JS API 给 agent
        └──────┬──────┘
               │
    ┌──────────┴──────────┐
    │  Claude Code / Codex │  ← 任意支持 skill 的 agent
    │  Cursor / 自定义      │     写 JS snippet 驱动浏览器
    └─────────────────────┘

三层分离:


十、适用 / 不适用场景

适合

不适合


十一、安全和隐私


十二、使用建议

写具体的 prompt。 模糊指令效果差。好的 prompt 应包含:目标 URL、要提取的字段、输出格式(Markdown 表格/JSON)、遇到不确定时如何处理。

# 差
/ego-browser check my orders

# 好
/ego-browser go to amazon.com/your-orders, extract the last 5 orders
as a markdown table with columns: date, item name, price, status.
If any field is unclear, mark it as "N/A".

用并行 Space 提速。 开两个 agent session,各给一个浏览器任务,它们在不同 Space 同时执行。

把 agent 当并行工位而非你的替身。 你在主浏览器干活,agent 在旁边的 Space 默默跑任务,跑完了来看结果。


十三、与同类工具对比

ego (lite) Playwright / Puppeteer Browser Use agent-browser (Vercel)
执行方式 JS 代码一次执行 逐步 API 调用 LLM loop 逐步 CLI 逐步
登录态 共享你的 需重新登录 需重新登录 需重新登录
CAPTCHA 极少触发 经常触发 经常触发 经常触发
多任务并行 Space 隔离 多实例 单实例 单实例
数据存储 本地 本地 云端(付费) 取决于部署
价格 免费 免费 按量付费 免费
日常浏览器 可替代 Chrome 不是浏览器 不是浏览器 不是浏览器
平台 macOS(Win/Linux 待上线) 全平台 全平台 全平台

十四、社区反馈(HN 讨论摘要)

从 Hacker News 讨论 的关键观点:


资源链接


ego (lite) 的核心价值是"让 agent 用你的浏览器、你的登录态干活,但不抢你的屏幕"。如果你的 agent 工作流涉及大量需要登录的 Web 操作,这工具值得一试——免费、本地、开箱即用。当前限制是只支持 macOS。